---
title: Overview of the Nx Docker Plugin
description: The Nx Plugin for Docker contains executors and utilities for building and publishing docker images within an Nx workspace.
keywords: [docker]
sidebar:
  label: Introduction
filter: 'type:References'
---

The Nx Plugin for Docker contains executors and utilities for building and publishing docker images within an Nx workspace.
Using the `@nx/docker` [Inference Plugin](/docs/concepts/inferred-tasks), Nx will automatically detect `Dockerfile`'s in your workspace and provide a `docker:build` and `docker:run` target for each.
It will also provide a `nx-release-publish` target for publishing docker images to a registry.

## Installation

In any Nx workspace, you can install `@nx/docker` by running the following command:

```shell
nx add @nx/docker
```

This will install the correct version of `@nx/docker` to match the version of Nx you are using.

{% aside title="Minimum Nx Version" type="caution" %}
The `@nx/docker` plugin only became available in Nx 21.4.0-beta.9. Your Nx Workspace will need to be on this version or higher to use it.
{% /aside %}

### How @nx/docker Infers Tasks

The `@nx/docker` plugin will create a task for any project that has a Dockerfile present. It will infer the following tasks:

- `docker:build`
- `docker:run`
- `nx-release-publish`

### View Inferred Tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project` in the command line.

### @nx/docker Configuration

The `@nx/docker` plugin is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": "docker:build",
        "runTarget": "docker:run"
      }
    }
  ]
}
```

The `buildTarget` and `runTarget` options control the names of the inferred Docker tasks. The default names are `docker:build` and `docker:run`.

### Advanced Plugin Configuration

The `buildTarget` and `runTarget` options can be configured as objects to provide additional customization beyond just naming the targets. This allows you to pass custom arguments, set environment variables, and use pattern interpolation.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "docker:build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "project={projectName}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1"
          },
          "envFile": ".env.docker",
          "cwd": "{projectRoot}/docker"
        },
        "runTarget": {
          "name": "docker:run",
          "args": ["--rm"],
          "env": {
            "NODE_ENV": "production"
          }
        }
      }
    }
  ]
}
```

#### Configuration Properties

When using the object format, the following properties are available:

- **`name`** (string, required): The name of the inferred target
- **`args`** (string[], optional): Additional arguments to pass to the Docker command. Supports pattern interpolation.
- **`env`** (object, optional): Environment variables to set when running the Docker command. Values support pattern interpolation.
- **`envFile`** (string, optional): Path to an environment file to load
- **`cwd`** (string, optional): Working directory for the command. Supports pattern interpolation.

#### Pattern Interpolation

All string values in the configuration support pattern interpolation using the following tokens:

- **`{projectName}`** - The name of the project from `project.json` or `package.json`
- **`{projectRoot}`** - The root directory of the project (e.g., `apps/api`)
- **`{imageRef}`** - The default image reference derived from the project root (e.g., `apps-api`)
- **`{currentDate}`** - Current date in ISO format (e.g., `2025-01-30T14:30:00.000Z`)
- **`{currentDate|FORMAT}`** - Current date with custom formatting (e.g., `{currentDate|YYYY.MM.DD}` → `2025.01.30`)
- **`{commitSha}`** - Full Git commit SHA
- **`{shortCommitSha}`** - First 7 characters of the commit SHA
- **`{env.VAR_NAME}`** - Environment variable values (e.g., `{env.BUILD_NUMBER}`)

Date formatting supports these tokens: `YYYY` (year), `YY` (2-digit year), `MM` (month), `DD` (day), `HH` (hours), `mm` (minutes), `ss` (seconds).

#### Example: Multi-Platform Build with Metadata

Here's a practical example that builds Docker images for multiple platforms and includes build metadata:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "org.opencontainers.image.title={projectName}",
            "--label",
            "org.opencontainers.image.source={projectRoot}",
            "--label",
            "org.opencontainers.image.revision={commitSha}",
            "--label",
            "org.opencontainers.image.created={currentDate}",
            "--build-arg",
            "BUILD_DATE={currentDate|YYYY-MM-DD}",
            "--build-arg",
            "VERSION={env.VERSION}",
            "--tag",
            "{imageRef}:{currentDate|YYMMDD}.{shortCommitSha}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1",
            "IMAGE_NAME": "{imageRef}"
          }
        },
        "runTarget": {
          "name": "run",
          "args": [
            "--rm",
            "--publish",
            "3000:3000",
            "--env",
            "NODE_ENV=production"
          ]
        }
      }
    }
  ]
}
```

This configuration:

- Builds for both AMD64 and ARM64 architectures
- Adds OpenContainers metadata labels with project information
- Tags images with a calendar version and commit SHA (e.g., `my-app:250130.abc1234`)
- Enables Docker BuildKit for improved build performance
- Injects build arguments and environment variables from the CI/CD pipeline

## Using Nx Release to Publish Docker Images

The `@nx/docker` plugin provides a `nx-release-publish` target for publishing docker images to a registry.
[Nx Release](/docs/features/manage-releases) was also updated to support versioning docker images, generating changelogs, and publishing docker images to a registry through a single command.

You can learn more about how to manage releases for Docker Images in the [Release Docker Images](/docs/guides/nx-release/release-docker-images) guide.
